<!DOCTYPE html>
<!--
 Copyright (c) 2010 - 2019 TU Wien ACIN, fortiss GmbH
 			   2019 Johannes Kepler University Linz
 			   2019 Andrea Zoitl
  
 This program and the accompanying materials are made available under the
 terms of the Eclipse Public License 2.0 which is available at
 http://www.eclipse.org/legal/epl-2.0.

 SPDX-License-Identifier: EPL-2.0
 
 Contributors:
   Carolyn Oates, Alois Zoitl, Monika Wenger, Milan Vathoopan, Jose Cabral
     - initial API and implementation and/or initial documentation
   Bianca Wiesmayr
     - adapting, restructuring and extending the installation tutorial
   Andrea Zoitl
     - improved readability, updated Help ToC
-->

<html lang="en">
<head>
	<meta http-equiv="Content-Type" content="text/html; charset=utf-8">
	<title>Installation</title>
	<link rel="stylesheet" type="text/css" href="../help.css">
</head>

<body>

<h1 id="topOfPage">Installation</h1>

<!--********************************************************************************************-->

<h2 id="4DIAC-IDE">4diac&nbsp;IDE</h2>
<p>The installation of 4diac&nbsp;IDE is independent of the operating system. 
In order to run 4diac&nbsp;IDE, you require at least <a href="http://www.oracle.com/technetwork/java/javase/downloads/index.html" target="_blank">Java 8</a>.</p>

<p>To install 4diac&nbsp;IDE, simply download the latest version for your operating system under <a href="https://www.eclipse.org/4diac/en_dow.php" target="_blank">downloads</a>. 
Unzip it to any desired folder and start the 4diac&nbsp;IDE. 
It already contains a Function Block library. 
If you only want to use available Function Blocks, you are ready to go.</p>

<!--*********************-->

<h3 id="ownIDE">Building Your own 4diac&nbsp;IDE From Source</h3>

<p>Running 4diac&nbsp;IDE from source has the advantage that you can easily keep up with the developments performed in the Git repository. 
If you want to run 4diac&nbsp;IDE from source, follow the <a href="../../html/development/building4diac.html#buildFromSource" target="_blank">installation steps</a>.
This option aims mainly at 4diac IDE developers or people who wish to extend 4diac IDE.</p>

<!--********************************************************************************************-->

<h2 id="4DIAC-FORTE">4diac&nbsp;FORTE</h2>
<p id="precompiledFORTE">4diac&nbsp;FORTE can be used in two ways: 
For conducting first experiments with Eclipse 4diac, you can use the pre-built version of 4diac&nbsp;FORTE which is available as <a href="https://www.eclipse.org/4diac/en_dow.php" target="_blank">download</a> for Linux and Windows.  
It can be used for applications unless you need own Function Blocks.

The step by step tutorial will direct you to making a simple application with 4diac&nbsp;IDE and pre-built 4diac&nbsp;FORTE. 
If you want to start using 4diac&nbsp;IDE right away, you can skip the rest of the page and go directly to the <a href="../../html/4diacIDE/overview.html">step by step tutorial</a> or the <a href="../../html/startHere/startHere.html">Start&nbsp;Here-page</a>.</p>
If you want to develop your own Function Blocks or to run 4diac&nbsp;FORTE on control devices, you have to download and set up 4diac&nbsp;FORTE for the specific platform you are using as shown in the next sections.

<!--*********************-->

<h3 id="ownFORTE">Building 4diac&nbsp;FORTE From Source</h3>
<p>In order to use own Function Blocks, you will need to build 4diac&nbsp;FORTE from the source code. 
In this section, the details for Windows and Unix-based systems are explained, since most user's first test is done on these platforms. 
For other platforms, links are provided <a href="#forteOtherPlatforms">here</a>.</p> 

<p  id="FORTEsteps">You'll need to perform several steps:</p>
<ol>
	<li> Install a compiler for <a href="#FORTEWindows">Windows</a> or <a href="#FORTEUnix">Unix-based systems</a> </li>
	<li> Install <a href="#FORTEcmake">cmake</a></li>
	<li> Create a <a href="#FORTEfolders">folder tree</a></li>
	<li> Download the 4diac&nbsp;FORTE source code as zip-File <a href="https://www.eclipse.org/4diac/en_dow.php" target="_blank">here</a></li>
	<li> Extract the source code to your desired 4diac&nbsp;FORTE source folder</li>
	<li> <a href="#generateFilesForCompiling">Build a project with CMake</a></li>
	<li> <a href="#FORTEcompile">Compile</a> the project</li>
	<li> <a href="#externalModules">Add external modules</a>: your own FBs</li>
	<li> (optional) Install a development environment for C++ such as <a href="../../html/installation/eclipse.html">Eclipse</a> or <a href="../../html/installation/visualStudio.html">MS Visual Studio</a>
</ol>

<!--*********************-->

<h4 id="FORTEWindows">C++ Compiler for Windows</h4>
<p>First of all, you need to install a C++ compiler. Download and installation are described here:</p>
				<ul>
					<li><a href="../../html/installation/minGW.html">Setting up MinGW-w64 (recommended) </a></li>
					<li><a href="../../html/installation/cygwin.html">Setting up Cygwin </a></li>
					<li><a href="../../html/installation/visualStudio.html">Setting up Visual Studio</a></li>
		      </ul> 
   <p>The following installation instructions are based on MinGW-w64 which is therefore recommended for inexperienced users. 
   If you plan to contribute to 4diac&nbsp;FORTE as a developer, you will need an IDE such as Eclipse or MS Visual Studio. 
   The latter already comes with a compiler and therefore, you don't need to install a separate compiler.
   Eclipse users, however, are recommended to install MinGW-w64.</p>
   
<a href="#FORTEsteps">back</a>

<!--*********************-->

<h4 id="FORTEUnix">C++ Compiler for Unix-based Systems</h4>
<p>In Unix-like systems (Linux, Raspberry Pi, ...), you need to install the packages binutils, gcc, gdb and make. </p>

<a href="#FORTEsteps">back</a>

<!--*********************-->

<h4 id="FORTEcmake">Install CMake</h4>
<p>The open source software CMake allows generating a C++ project or makefile from the source code.
   We will use it to generate a project to compile. 
   It generates specific files from the general source code for your target platform and compiler. 
   Additionally, it is used to configure your 4diac&nbsp;FORTE.</p>

<p>For Windows, you can download CMake <a href="https://cmake.org/download/" target="_blank">here</a>. 
Follow the steps in the installation wizard and be sure to select adding CMake to the PATH variable in the respective step.
   To avoid any problems, you should choose an installation path that does not contain spaces.</p>

<p>For Linux, simply install the package CMake provided by your distribution.</p>

<p><a href="#FORTEsteps">back</a></p>

<!--*********************-->

<h4 id="FORTEfolders">Create a Folder Tree</h4>
<p>You need to create a folder where you save all files of your 4diac&nbsp;FORTE. 
Again, the file path should not contain any spaces.
We recommend using a main folder <span class="specificText">C:/FORTE_dev</span> (in this tutorial, we refer to it as FORTE_FOLDER_ROOT).
Within that folder, use subfolders for the code (e.g., org.eclipse.forte), the built version (e.g., build) and your own modules (e.g., ext_modules).
 </p>

<p>	The 4diac&nbsp;FORTE source code is available for download as zip-File <a href="https://www.eclipse.org/4diac/en_dow.php" target="_blank">here</a>.
Extract the source code to your desired 4diac&nbsp;FORTE source folder, e.g. C:/FORTE_dev/org.eclipse.forte).


<p><a href="#FORTEsteps">back</a></p>

<!--*********************-->

<h4 id="generateFilesForCompiling">Generate 4diac FORTE Makefiles with CMake</h4>

<p>Once you have the 4diac&nbsp;FORTE code on your computer, you must generate Makefiles to be compiled. 
Why? 
Because FORTE is prepared for many platforms and many features can be enabled, disabled or tuned. 
In order to facilitate these settings, <a href="#FORTEcmake">CMake</a> is used. 
For beginners, we recommend using the GUI tool that comes with CMake.</p>

<ol>
	
	<li><p>Start the CMake-GUI.</p></li>
	
	<li><p>First, you have to select the source directory <span class="folderLocation">FORTE_FOLDER_ROOT/org.eclipse.forte</span> (1), to which you have extracted the source code.</p>
	
	<p>Next, you select the directory, to which you build the binaries (2) (e.g., <span class="folderLocation">FORTE_FOLDER_ROOT/bin/posix</span> or <span class="folderLocation">FORTE_FOLDER_ROOT/bin/win32</span>,...).
	This is the output directory (referred to as OUTPUT_FOLDER in the tutorial), to which CMake puts configuration data and any build files.
	
	<p>The files are required for compiling in the next step. Press the <span class="button4diac">Configure</span> button (3) at the bottom. 
	If you are asked to create a folder that doesn't exist, confirm.</p>
	
	<div><img src="../../html/installation/img/CMakeFirstStep.png" alt="First step in CMake"></div></li>
	
	<li><p>In the pop up window select your project type, which depends on your target system. 
	CMake needs to know whether to export the files as a project for Visual Studio, Eclipse, or another, and the compiler you will use to compile the executable.<br>
	If you installed <span class="specificText">MinGW-w64 for Windows</span>, select here <span class="specificText">Unix makefiles</span>,  tick <span class="specificText">Use default native compilers</span> and click Finish. </p>
	<p>As a Linux user, also select "Unix makefiles".
	For other setups, check the respective installation page.
	 In this step, you would select the cross-compiler used if you are compiling for another platform
     (for example, compiling for a Raspberry Pi or a PLC from a Windows or a Linux computer).
	  </p>
	
	<div><img src="../../html/installation/img/CMakeSelectCompiler.png" alt="Select compiler in CMake"></div></li>
	
	<li><p>After selecting the type of project and compiler, click Generate.</p>
	<p>You may get an error message "No valid architecture chosen", click Okay.
	 The CMake main window shows now a list of red marked options.
	 The color red doesn't mark errors, but that these rows were affected by the last configuration, so they need to be checked. 
	 These options allow you to configure your 4diac&nbsp;FORTE build. 
	 You should set at least the following parameters:</p>
	 	<ul>
	 		<li> select the target architecture	using the <span class="specificText">FORTE_ARCHITECTURE</span> option:<br>
	 		     <span class="specificText">win32</span> for Windows with MinGW-w64<br>
	 		     <span class="specificText">posix</span> for Linux<br>
	 		     For other setups, check the respective installation page.</li>
	 		<li> select the modules with the Function Block libraries you wish to enable 
	 		     (a basic configuration uses <span class="specificText">FORTE_MODULE_CONVERT</span>, <span class="specificText">FORTE_MODULE_IEC61131</span> and <span class="specificText">FORTE_MODULE_UTILS</span>)</li>
	    	<li> choose the <span class="specificText">CMAKE_BUILD_TYPE</span> by adding the value <span class="specificText">Debug</span> or <span class="specificText">Release</span> 
	    </ul>

	<div><img src="../../html/installation/img/CMakeBasicConfig.png" alt="Basic Configuration in CMake"></div></li>
	
	<li><p>After you change some options in CMake, you must press Configure again until no row appears red.</p></li>
	
	<li><p>Finally, press the <span class="button4diac">Generate</span> button to create the project files in OUTPUT_FOLDER.</p></li>
</ol>
<a href="#FORTEsteps">back</a>


<!--*********************-->

<h4 id="FORTEcompile">Compile the Project</h4>

<p>The last step is compiling the generated project.
It generates the 4diac FORTE executable.
 This step depends on the project output you selected in the previous step. 
 For Windows with MinGW-w64, open the command prompt (cmd). 
 The command cd enters a certain directory. 
 Therefore, you need to choose the OUTPUT_FOLDER you indicated in CMake.
 If you followed the recommended structure, it is C:\FORTE_dev\build\win32.<br>
 Enter:</p>
 <div class="code">cd C:\FORTE_dev\build\win32
make</div>
 For Linux, open the terminal and go to the OUTPUT_FOLDER:
		   <div class="code">cd FORTE_FOLDER_ROOT/bin/posix
make</div> <br>

<p>For the development with 4diac&nbsp;FORTE, understanding the general file structure is helpful. 
Therefore, the essential parts as well as the Makefiles which are important for the configuration and compilation of 4diac&nbsp;FORTE are listed:
<ul>
	<li><span class="folderLocation">src/modules</span>: this folder contains the source code (cpp, h) of all Function Blocks available for 4diac&nbsp;FORTE </li>
	<li><span class="folderLocation">bin/[YOUR_SYSTEM]/src</span>: contains the 4diac&nbsp;FORTE executable after compilation</li>
	<li><span class="folderLocation">bin/[YOUR_SYSTEM]/src_gen</span>: contains the object files generated during compilation</li>
</ul>

<a href="#FORTEsteps">back</a>

<!--*********************-->

<h4 id="externalModules">Add External Modules</h4>

<p>Let's see how to add your own Function Blocks to 4diac&nbsp;FORTE.
When you create and export your own types, you need to add them to your compilation. 
The export is described in the <a href="../../html/4diacIDE/createOwnTypes.html#exportTypes">tutorial step 4</a>.
As an example, we show how to add the three FBs BasicTest, CompositeTest, and ServiceTest from this tutorial.
The name of the module will be EXAMPLE_TEST. 
Follow the instructions:</p>
<ol>
	<li>In step 3, we created a folder in your system that will hold all future modules. 
	We called it <span class="folderLocation">ext_modules</span></li>
	<li>Create a subfolder called EXAMPLE_TEST 
	(the name doesn't need to be exactly the name of the module, but this helps organizing) and access it.</li>
	<li>Put all six files into EXAMPLE_TEST (a .cpp and .h file for each FB).</li>
	<li>Create a file called <span class="fileLocation">CMakeLists.txt</span> (this exact name is mandatory).
	<div><img src="../../html/installation/img/modulesFiles.png" alt="File Structure to add modules"></div></li>
	<li>Inside write:
	<div class="code">forte_add_module(EXAMPLE_TEST "Example test module")

forte_add_sourcefile_hcpp(BasicTest)
forte_add_sourcefile_hcpp(CompositeTest)
forte_add_sourcefile_hcpp(ServiceTest)</div>

	and save. 
	The first parameter of <span class="specificText">forte_add_module</span> is the name of the module; 
	the second is a comment. 
	The <span class="specificText">forte_add_sourcefile_hcpp</span> command tells CMake which .cpp and .h files to compile. 
	You can use <span class="specificText">forte_add_subdirectory</span> to include subdirectories with own <span class="fileLocation">CMakeLists.txt</span> files.</li>
	<li>In CMake, please verify that the source code folder is still FORTE_FOLDER_ROOT.
	It is <span class="specificText">not</span> changed to ext_modules.
	Press Configure.
	There's a variable called <span class="specificText">FORTE_EXTERNAL_MODULES_DIRECTORY</span>. 
	Set this to the <span class="folderLocation">ext_modules</span> folder.</li>
	<li>When pressing Configure again, a variable called <span class="specificText">FORTE_MODULE_EXAMPLE_TEST</span> will appear. 
	Checking the box will include the module in compilation.
	<div><img src="../../html/installation/img/modulesCMake.png" alt="CMake configuration for external modules"></div></li>
	<li>After setting all desired variables, do the same as before: Generate and then <a href="#FORTEcompile">compile</a>.</li>
</ol>
<a href="#FORTEsteps">back</a>

<!--********************************************************************************************-->
	
<h2 id="forteOtherPlatforms">Building 4diac&nbsp;FORTE for Other Platforms</h2>
	<ul>
		<li><a href="../../html/installation/raspi.html">Setting up 4diac&nbsp;FORTE for RaspberryPi</a></li>
		<li><a href="../../html/installation/raspberrySPS.html">Setting up 4diac&nbsp;FORTE for RaspberryPi SPS</a></li>
		<li><a href="../../html/installation/wago.html">Setting up 4diac&nbsp;FORTE for Wago PFCs SPS</a></li>
		<li><a href="../../html/installation/legoMindstormEv3.html">Setting up 4diac&nbsp;FORTE for Lego Mindstorms EV3</a></li>
		<li><a href="../../html/installation/mindstorms.html">Setting up 4diac&nbsp;FORTE for Lego Mindstorms</a></li>
		<li><a href="../../html/installation/freeRTOSLwIP.html">Setting up 4diac&nbsp;FORTE for freeRTOS + LwIP</a></li>
	</ul>

<!--********************************************************************************************-->

<h1 id="whereToGoFromHere">Where to go from here?</h1>

<p>Now that you installed the required tools, it's time to start using them. 
Take a look at the tutorials - A step by step guide:</p>

<p><a href="../../html/4diacIDE/overview.html">Step 0 - 4diac IDE Overview</a></p>

<p>If you want to go back to the Where to Start page, we leave you here a fast access:</p>

<p><a href="../../html/startHere/startHere.html">Where to Start</a></p>

<p class="goToTop">Or <a href="#topOfPage">Go to top</a></p>

</body>
</html>
